home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 551-575 / disk_570 / gadtoolsbox / gadtoolsbox.doc < prev    next >
Text File  |  1992-05-06  |  46KB  |  909 lines
  1.  
  2.                       GadToolsBox v1.0 (The Sequel)
  3.  
  4.                    (c) Copyright 1991 Jaba Development
  5.                       Written using  DICE C v2.6 by
  6.                             Jan van den Baard
  7.  
  8.                                User Manual
  9.  
  10.  
  11.   Disclaimer................ 1
  12.   Copyright/Distribution.... 2
  13.   Electronic Distribution... 3
  14.   Introduction.............. 4
  15.   Requirements.............. 5
  16.   Starting GadToolsBox...... 6
  17.   Making a Gadget........... 7
  18.   Program Menus............. 8
  19.     The Project Menu........ 8.1
  20.     The Gadgets Menu........ 8.2
  21.     The Window Menu......... 8.3
  22.     The Screen Menu......... 8.4
  23.     The Menus Menu.......... 8.5
  24.   Gadget Kind Requester..... 9
  25.     The CheckBox Gadget..... 9.1
  26.     The Integer Gadget...... 9.2
  27.     The ListView Gadget..... 9.3
  28.     The Mx Gadget........... 9.4
  29.     The Cycle Gadget........ 9.5
  30.     The Palette Gadget...... 9.6
  31.     The Scroller Gadget..... 9.7
  32.     The Slider Gadget....... 9.8
  33.     The String Gadget....... 9.9
  34.   Menu Requesters........... 10
  35.     The Menu Requester...... 10.1
  36.     The (Sub)Item Requester. 10.2
  37.   The Generated Source...... 11
  38.   Notes..................... 12
  39.  
  40.  »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  41.  » 1) Disclaimer                                                           »
  42.  »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  43.  The author cannot be held liable for the  suitability or  accuracy  of this
  44.  manual  and/or  the  program(s)  it  describes.   Any  damage  directly  or
  45.  indirectly caused by the use or misuse of  this manual  and/or the  program
  46.  it describes is the sole responsibility of the user her/him self.
  47.  
  48.  »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  49.  » 2) Copyright/Distribution                                               »
  50.  »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  51.  GadToolsBox, (c) Copyright 1991 Jaba Development. All rights reserved. This
  52.  Program is FREEWARE so no financial donations are required ( but welcome ).
  53.  This   program  may  be  freely  distributed  as  long  as all source code,
  54.  documentation and executable(s) remain unchanged and are included  with the
  55.  distribution. Also no profit is to be made  by  selling  this  program. You
  56.  may not charge more than Fred Fish  does for a  single  library disk.  This
  57.  program may be distributed on disk magazines, cover disks etc.  When you do
  58.  decide to distribute this program on a disk magazine  or cover disk  please
  59.  send me a copy of the distribution. When you use this program on a  regular
  60.  base I would appreciate a postcard of your home town. If  this  program  is
  61.  used  to  create a  GadTools user interface  for  commercial  or  shareware
  62.  programs I would appreciate a little note about  this in  the program  it's
  63.  documentation.
  64.  
  65.  »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  66.  » 3) Electronic Distribution                                                 »
  67.  »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  68.  It is allowed for non-commercial BBSs to distribute  an archive  with  only
  69.  the following files in it to save your users some  money when they  want to
  70.  download this program.
  71.  
  72.     GadToolsBox             - Main Program
  73.     GadToolsBox.info        - Main Program icon.
  74.     GadToolsBox.DOC         - Main Program Manual (This file)
  75.     nofrag.library          - Shared library ( (c)1991 Jaba Development )
  76.  
  77.  You may NOT upload this or any  other form of  this  software on  BBSs that
  78.  claim copyrights on the uploaded material!
  79.  
  80.  »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  81.  » 4) Introduction                                                         »
  82.  »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  83.  GadToolsBox  is a program that will save you a gigantic amount of time  and
  84.  anguish  in  creating  a  GadTools  user interface  for your programs. This
  85.  program is  a followup of  my other  source  generator  "PowerSource". It's
  86.  main purpose is to let you create  your user  interface without  having  to
  87.  type in the necessary code and structures yourself.
  88.  
  89.  »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  90.  » 5) Requirements                                                         »
  91.  »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  92.  GadToolsBox was programmed with DICE C v2.6 (Thanks Matt)  on an Amiga 2500
  93.  Kickstart  V37.175  Workbench  V37.67  with  5 MB  memory  +  ECS  +  A2630
  94.  accelerator card + 52 MB harddisk. It should however run happely on  a 1 MB
  95.  machine without a harddisk and special chips. It MUST have Kickstart  V37++
  96.  and Workbench  V37++.  You can try  it on Kickstart  V36 but I don't really
  97.  know if it will work properly.  A  C  Compiler ( try registering DICE ) and
  98.  or  an assembler with the  2.0 headers  can  also come  in  handy  when you
  99.  try to compile/assemble the generated source.
  100.  
  101.  »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  102.  » 6) Starting GadToolsBox                                                 »
  103.  »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  104.  You can start GadToolsBox from either the Shell or the Workbench.  To start
  105.  GadToolsBox from the Shell you must type the following:
  106.  
  107.     GadToolsBox [filename]
  108.  
  109.  Where filename is an optional name of a previously  created file  which you
  110.  want to edit. To  start  GadToolsBox  from  the  workbench  you must either
  111.  double-click the program it's icon or one of the ".G" icons.  When you have
  112.  started PowerSource without any arguments a window appears in the middle of
  113.  the screen. With this window we can select the Screen type on which we want
  114.  to edit  the  GadTools  user  interface.  In this  window  you will see the
  115.  following gadgets:
  116.  
  117.     Available modes     » In this gadget you see a list of available display
  118.                           modes.  Just click on the  desired  display  mode.
  119.                           NOTE: The program currently  only  checks  for the
  120.                                 availability of the LORES, HIRES and  SUPER-
  121.                                 HIRES  modes  for  both  the  PAL  and  NTSC
  122.                                 monitors.
  123.  
  124.     Depth               » This slider gadget  lets  you  adjust  the  screen
  125.                           depth. The screen depth  determines the  amount of
  126.                           available colors.
  127.  
  128.                           Depth = 1, Colors = 2
  129.                           Depth = 2, Colors = 4
  130.                           Depth = 3, Colors = 8
  131.                           Depth = 4, Colors = 16
  132.                           Depth = 5, Colors = 32
  133.  
  134.     OK                  » When this gadget is clicked the  program will  try
  135.                           to open the desired screen and start the editing.
  136.  
  137.     CANCEL              » Clicking on this gadget will  quit when you got in
  138.                           this window  upon program  startup  or cancel  the
  139.                           operation when you got in this window by selecting
  140.                           "New" from the "Project" menu.
  141.  
  142.  If everything went OK you now see the selected screen with a little  window
  143.  on it.
  144.  
  145.  »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  146.  » 7) Making a Gadget                                                      »
  147.  »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  148.  To make a gadget is quite simple. Move the mouse pointer to the place where
  149.  you want the top-left of the gadget to be. Now click the left  mouse-button
  150.  once and move the mouse. You'll see a  box  which will  size  according  to
  151.  your mouse moves.  When the box  is  the size  you want it  click the  left
  152.  mouse button again. Now a window pops up  which  allows  you  to  edit  the
  153.  gadget kind specifics ( refer to the "Gadget Kind Requester" for more info)
  154.  After you have edited the gadget specifics click  on  OK and the  gadget is
  155.  on the window ready to be played around with.
  156.  
  157.  »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  158.  » 8) Program Menus                                                        »
  159.  »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  160.  GadToolsBox  uses  a set  of menus  to let you  control  the  program.  The
  161.  following describes each menu and it's items.
  162.  
  163.  »»» 8.1) The Project Menu
  164.  
  165.  About............. This opens a little window  with some  information about
  166.                     the copyright, author and memory  status.  Just click on
  167.                     the CONTINUE gadget to get rid of it.
  168.  
  169.  New............... Reset's the program to the default deleting every change
  170.                     made sofar. When there are changes  made  that  are  not
  171.                     saved yet the program asks for confirmation.
  172.  
  173.  Load.............. This opens the ASL FileRequester in which you can select
  174.                     the file you want to load.  The  program can  only  load
  175.                     binaries created by GadToolsBox.  Any other kind of file
  176.                     will simply be refused.
  177.  
  178.  Save.............. This will  save  the  GadTools  interface  to  the  file
  179.                     specified in the  ASL FileRequester.  NOTE: The  default
  180.                     name is "unnamed.g"
  181.  
  182.  Save As........... This opens the ASL FileRequester in which you can select
  183.                     the  path  and  file  name  under  which   the  GadTools
  184.                     interface is saved.
  185.  
  186.  Generate Source...
  187.     C.............. This opens the ASL FileRequester in which you can select
  188.                     the path and  file  name  under  which  the  generated C
  189.                     source will be generated.
  190.  
  191.     Assembler...... The same as C only the generated source will be in 68000
  192.                     Assembler.
  193.  
  194.  Preferences....... This opens the preferences window.  In this  window  you
  195.                     will see the following gadgets:
  196.  
  197.                     Static Data        » When  this is switched  on  the  C
  198.                                          source  will only  contain  static
  199.                                          data and routines.
  200.  
  201.                     RAW Asm source     » When  this  is  switched   on  the
  202.                                          Assembler source generated can  be
  203.                                          assembled   without  the   OS  2.0
  204.                                          headers.
  205.  
  206.                     Coordinates        » If you want  the  mouse coordinates
  207.                                          to  be   displayed  constantly  you
  208.                                          should switch this gadget on.
  209.  
  210.                     Write Icon         » When  this  is  switched  on  every
  211.                                          binary written by  GadToolsBox  has
  212.                                          an icon to accompany it.
  213.  
  214.                     Count ID from      » In this gadget  you can  enter  the
  215.                                          ID number from  which  the  program
  216.                                          starts to count the gadget ID's.
  217.  
  218.                     Project Prefix     » In  this  gadget  you  can  type  a
  219.                                          prefix which is used by the  source
  220.                                          generator. Refer to the  "Generated
  221.                                          Source" chapter for more info.
  222.  
  223.                     Save               » Opens  the  ASL  FileRequester   in
  224.                                          which you can select the  path  and
  225.                                          name under  which  the  preferences
  226.                                          are saved.
  227.  
  228.                     Load               » Opens  the  ASL  FileRequester   in
  229.                                          which you can select a  GadToolsBox
  230.                                          preferences file to load.
  231.  
  232.                     Use                » This tells GadToolsBox to  use  the
  233.                                          preferences you have set.
  234.  
  235.                     CANCEL             » This cancels the operation.
  236.  
  237.  Close Workbench... This will try to close the workbench screen so  that you
  238.                     can use the memory it took up. When this item reads Open
  239.                     Workbench it will try to open the Workbench screen again
  240.  
  241.  Quit.............. This will quit the program after asking for confirmation
  242.  
  243.  »»» 8.2) The Gadgets Menu
  244.  
  245.  In this menu some items will ask you to click a gadget to perform a certain
  246.  action.  When  you  accidentally activated one of those items you can abort
  247.  the routine by pressing the  ESC  (Escape)  key  when  the  question "CLICK
  248.  GADGET.." pops up in the screen title bar.
  249.  
  250.  Kind.............. This item has the  program  supported  gadget  kinds  as
  251.                     sub-items attached to it. Selecting  any of  these  sub-
  252.                     items will change the editing  for  that  gadget   kind.
  253.                     All GadTools gadget kinds except for the NUMBER and TEXT
  254.                     kinds are supported.
  255.  
  256.  Move a gadget..... This asks you to click on the gadget you  want to  move.
  257.                     When you click on a gadget a box  is drawed  around  it.
  258.                     Just move the box to where you want it and click on  the
  259.                     left mouse-button to confirm the place.
  260.  
  261.  Size a gadget..... This asks you to click on the gadget that  you  want  to
  262.                     re-size. When you click on a  gadget  a  box  is  drawed
  263.                     around the gadget. Just move  the mouse  to  adjust  the
  264.                     size of the box and click  on the  left  mouse-button to
  265.                     confirm  the  size.  NOTE:  The  minimum  possible  size
  266.                     depends on the gadget kind and the font size.
  267.  
  268.  Copy a gadget..... This ask you to click on the  gadget  you want  to copy.
  269.                     Clicking on the gadget you want to copy will draw  a box
  270.                     around the gadget which  you must  drag  to it's  place.
  271.                     Just click on  the  left  mouse-button to  confirm  it's
  272.                     place.
  273.  
  274.  Delete a gadget... This asks you to click on the gadget you want to delete.
  275.                     When you click on  the  gadget  to  delete  it  will  be
  276.                     removed and deallocated.
  277.  
  278.  Edit a gadget..... This  asks  you to click on the gadget you want to edit.
  279.                     Then the window for the specific  kind  of  gadget  will
  280.                     open.  Please  refer  to  the  "Gadget  Kind  Requester"
  281.                     chapter for more information about these windows.
  282.  
  283.  Join.............. This first asks you to click on a  ListView  gadget  you
  284.                     want to join. The the program asks you to  click on  the
  285.                     string gadget you want to join with the ListView gadget.
  286.                     The the routine  joins the  two gadgets  together.  This
  287.                     joining means that the String gadget will be filled with
  288.                     the  entry  name of a  clicked  entry  in  the  ListView
  289.                     gadget. NOTE:  Due  to  a  bug  (or something)  GadTools
  290.                     requires the String Gadget to be of  the same  Width  as
  291.                     the ListView gadget. This is done  automatically  by the
  292.                     program and it  cannot be  stopped.  Also  GadTools will
  293.                     force the string  gadget  directly  below  the  ListView
  294.                     gadget. This also cannot be stopped.
  295.  
  296.  Split............. This will ask you to click on a Joined gadget.  Now  you
  297.                     can click either  the  joined  ListView  gadget  or  the
  298.                     joined String Gadget and they will be split. NOTE: After
  299.                     the Gadgets has been split the string Gadget  returns to
  300.                     the place where it has been originally drawn.
  301.  
  302.  »»» 8.3) The Window Menu
  303.  
  304.  Edit Flags........ This opens a requester in  which  all window  flags  are
  305.                     listed using CheckBox gadgets. Just (de)select the flags
  306.                     you want. Clicking on OK will set these flags and CANCEL
  307.                     cancels  the  operation.   NOTE:  Only  the  SIZEGADGET,
  308.                     DRAGBAR,   DEPTHGADGET,   CLOSEGADGET,   SIZEBRIGHT  and
  309.                     SIZEBBOTTOM flags are (un)set on  the  edit  window. The
  310.                     rest of the flags will  only turn  up in  the  generated
  311.                     source code.
  312.  
  313.  Edit IDCMP........ This opens a requester in which all window  IDCMP  flags
  314.                     are listed using CheckBox gadgets.  Just  (de)select the
  315.                     flags you want. Clicking on OK will set these flags  and
  316.                     CANCEL  cancels  the  operation.   NOTE:   The  GadTools
  317.                     specific  IDCMP  flags  will  always be set according to
  318.                     the kind of gadgets on the window.
  319.  
  320.  Edit Tags......... This will open a window in  which  some  special  window
  321.                     tags can  be  edited.  In  the  window  you'll  see  the
  322.                     following  gadgets:
  323.  
  324.                     InnerWidth   » When   this   gadget   is  selected   the
  325.                                    generated    source    will    use    the
  326.                                    WA_InnerWidth Tag instead of the WA_Width
  327.                                    Tag. The value next to the gadget  is the
  328.                                    current window InnerWidth.
  329.  
  330.                     InnerHeight  » When   this   gadget   is  selected   the
  331.                                    generated    source    will    use    the
  332.                                    WA_InnerHeight   Tag   instead   of   the
  333.                                    WA_Height Tag.  The  value  next  to  the
  334.                                    gadget is the current window InnerHeight.
  335.  
  336.                     MouseQueue   » When this gadget is  selected the  source
  337.                                    will contain the  WA_MouseQueue  tag.  In
  338.                                    the string gadget next to this gadget you
  339.                                    can type the amount of MouseQueue's. NOTE
  340.                                    This value cannot be smaller than 1.
  341.  
  342.                     RptQueue     » When this gadget is  selected the  source
  343.                                    will contain the  WA_RptQueue tag. In the
  344.                                    string gadget next to this gadget you can
  345.                                    type the amount of RptQueue's. NOTE: This
  346.                                    value cannot be smaller than 1.
  347.  
  348.                     AutoAdjust   » Selecting this will cause  the  generated
  349.                                    source to contain the  WA_AutoAdjust tag.
  350.  
  351.                     Zoom         » When this gadget is selected the  WA_Zoom
  352.                                    is generated in the source  code.  In the
  353.                                    Left, Top, Width, Height gadgets  you can
  354.                                    type the Window it's alternate positions.
  355.  
  356.                     WindowTitle  » Type the Window title  in here.  If  this
  357.                                    Gadget is empty the WA_Title tag will not
  358.                                    be generated.
  359.  
  360.                     ScreenTitle  » Type the  Screen title in  here. If  this
  361.                                    Gadget is  empty the  WA_ScreenTitle  tag
  362.                                    will not be generated.
  363.  
  364.                     OK           » This will set  the  desired  changes  and
  365.                                    resume to editing.
  366.  
  367.                     CANCEL       » This will cancel the operation.
  368.  
  369.  Add a text........ This will open the  IntuiText  editor  window.  In  this
  370.                     window you'll find the following gadgets:
  371.  
  372.                     Enter Text   » In this gadget you must  type the  actual
  373.                                    text you want.
  374.  
  375.                     JAM1
  376.                     JAM2
  377.                     COMPLEMENT
  378.                     INVERSVID    » These four gadgets determine the drawmode
  379.                                    used to paint the text in the rastport.
  380.  
  381.                     FrontPen     » With this palette gadget  you can  select
  382.                                    the FrontPen (text) color  which is  used
  383.                                    to draw the text.
  384.  
  385.                     BackPen      » With this palette gadget  you can  select
  386.                                    the BackPen (background)  color  which is
  387.                                    used to draw the text.
  388.  
  389.                     OK           » This gadget will close the window and let
  390.                                    you position the text in the edit window.
  391.                                    Clicking on  the left  mouse-button  will
  392.                                    confirm the place.
  393.  
  394.                     CANCEL       » This will cancel the operation.
  395.  
  396.  Modify a text..... This will put up the text selection window if  there was
  397.                     more than one text added. In this text selection  window
  398.                     you'll see the following gadgets:
  399.  
  400.                     Available Texts » In  this  ListView  gadget  the  texts
  401.                                       currently   in   memory   are  listed.
  402.                                       Clicking on the text will select it.
  403.  
  404.                     OK              » This will  select  the  text  for  the
  405.                                       operation that has to be done.
  406.  
  407.                     CANCEL          » This will cancel the operation.
  408.  
  409.                     Now the IntuiText Editor opens  with the  selected  text
  410.                     already  in it.  Now you can edit  the text the  way you
  411.                     want.
  412.  
  413.  Delete a text..... This will put up the text selector  again if  more  than
  414.                     one text is added to the  window.  Just select  the text
  415.                     and it's gone. NOTE: When only one text is available the
  416.                     text is deleted immediately.
  417.  
  418.  Move a text....... The text selector pops up again if.... Now you can  move
  419.                     the text around in the edit window.  Just  click on  the
  420.                     left mouse-button to confirm it's new place.
  421.  
  422.  »»» 8.4) The Screen Menu
  423.  
  424.  Palette........... This will open the palette editor. In the palette editor
  425.                     you'll see the following gadgets:
  426.  
  427.                     Red         » With this slider gadget you can adjust the
  428.                                   Red intensity  of the  currently  selected
  429.                                   color.
  430.  
  431.                     Green       » With this slider gadget you can adjust the
  432.                                   Green intensity of the currently  selected
  433.                                   color.
  434.  
  435.                     Blue        » With this slider gadget you can adjust the
  436.                                   Blue intensity of the  currently  selected
  437.                                   color.
  438.  
  439.                     Colors      » This gadget consists of 2, 4, 8, 16 or  32
  440.                                   colored gadgets and a color indicator left
  441.                                   of it. Just click on the color you want to
  442.                                   edit to switch to editing that color.
  443.  
  444.                     OK          » This will close the Palette editor and set
  445.                                   the desired colors on the edit screen.
  446.  
  447.                     Reset       » This will reset all  colors to  what  they
  448.                                   where before the palette editor opened.
  449.  
  450.                     CANCEL      » This will first reset all colors  and then
  451.                                   exit the palette editor.
  452.  
  453.  Get Font.......... This will  open the ASL FontSelector for you to select a
  454.                     new font. To select a font you must first  click  on the
  455.                     desired font name and then enter or click on the desired
  456.                     font height. Clicking on Ok  will set the  font  on  the
  457.                     screen and clicking on Cancel will cancel the operation.
  458.  
  459.  Set DriPens....... This will open the DriPen editor.  DriPens are the  pens
  460.                     which the system uses to  give that  special new  OS 2.0
  461.                     look  to  the  window  and  gadgets etc.  The  following
  462.                     gadgets are in the DriPen editor:
  463.  
  464.                     Pens        » This cycle gadget is  used to  select  the
  465.                                   DriPen you want  to  edit.  The  following
  466.                                   DriPens are available:
  467.  
  468.                                   DETAILPEN
  469.                                       This  is  the  same  as  the  standard
  470.                                       NewScreen detailpen.
  471.  
  472.                                   BLOCKPEN
  473.                                       This  is  the  same  as  the  standard
  474.                                       NewScreen blockpen.
  475.  
  476.                                   TEXTPEN
  477.                                       This is  the  pen  used  to  draw  the
  478.                                       gadget text and the Window title.
  479.  
  480.                                   SHINEPEN
  481.                                       This is  the  pen  used  to  draw  the
  482.                                       "light-side" of the gadget and  window
  483.                                       borders.
  484.  
  485.                                   SHADOWPEN
  486.                                       This is  the  pen  used  to  draw  the
  487.                                       "dark-side"  of the gadget and  window
  488.                                       borders.
  489.  
  490.                                   FILLPEN
  491.                                       This is the pen used to  backfill  the
  492.                                       gadget  when  it's  clicked   and  the
  493.                                       window border when it's active.
  494.  
  495.                                   FILLTEXTPEN
  496.                                       This is the pen used to draw the  text
  497.                                       of a clicked  gadget  and  the  Window
  498.                                       title of an active window.
  499.  
  500.                                   BACKGROUNDPEN
  501.                                       This   pen  is   used   to   fill  the
  502.                                       background of an unselected gadget.
  503.  
  504.                                   HIGHLIGHTTEXTPEN
  505.                                       This pen is used to draw the text of a
  506.                                       gadget   with   the  HighLight  switch
  507.                                       turned on.
  508.  
  509.                     OK          » Clicking  on  this  gadget  will  set  the
  510.                                   desired DriPens.
  511.  
  512.                     CANCEL      » This will cancel the operation.
  513.  
  514.  Edit Tags......... This will open the screen tags  window.  In  this window
  515.                     the following gadgets are located:
  516.  
  517.                     AutoScroll  » With this  gadget  checked  the  generated
  518.                                   source will contain the SA_AutoScroll tag.
  519.  
  520.                     Type        » This cycle gadget has the supported screen
  521.                                   types in it:
  522.  
  523.                                   CUSTOMSCREEN
  524.                                        The generated source will contain the
  525.                                        screen tags and data. The window will
  526.                                        use this screen to open on.
  527.  
  528.                                   WBENCHSCREEN
  529.                                        The generated source will not contain
  530.                                        the screen tags and data.  The window
  531.                                        will use the Workbench screen to open
  532.                                        on.
  533.  
  534.                                   CUSTOMSCREEN
  535.                                        The generated source will not contain
  536.                                        the screen tags and data.  The window
  537.                                        will use the default public screen to
  538.                                        open on.
  539.  
  540.                     OK          » This will set the desired tags.
  541.  
  542.                     CANCEL      » This will cancel the operation.
  543.  
  544.  »»» 8.5) The Menus Menu
  545.  
  546.  Edit Menus........ This will open the Menu Editor  window in which  you can
  547.                     edit   a   complete  menu-strip.   Refer  to  the  "Menu
  548.                     Requesters" chapter for more information.
  549.  
  550.  Test Menus........ This will setup the menus,  items  and  subitems  to  be
  551.                     tested by you. When the message "TESTING MENUS!  ESC  TO
  552.                     QUIT..." is printed  in  the  screen title  bar you  can
  553.                     browse  through  the  menus  like  you  normally do. You
  554.                     should press the ESC (escape) key to resume to editing.
  555.  
  556.  »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  557.  » 9) Gadget Kind Requester                                                »
  558.  »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  559.  GadToolsBox supports 10 gadget kinds which all  have their  own  window  in
  560.  which the gadget kind specifics can be edited. The following gadgets can be
  561.  found in all gadget kind requesters and are there for the same reason:
  562.  
  563.  Text           » In this gadget you can type the  text which  is  displayed
  564.                   with the gadget.
  565.  
  566.  Label          » In this gadget you can type the source code label which is
  567.                   used to define  some  important  values  in the  generated
  568.                   source. Refer to the "Generated Source"  chapter  for more
  569.                   information.
  570.  
  571.  Underscore     » When  this  gadget  is  selected   the  character  in  the
  572.                   GadgetText preceeded  by a '_' will  be  underlined  which
  573.                   specifies the keyboard shortcut.
  574.  
  575.  Disabled       » When this gadget is selected the gadget will be  disabled.
  576.                   The gadget will only be disabled in the  generated source.
  577.                   NOTE: Not all gadgets support this switch.
  578.  
  579.  High Label     » This tells that  the  GadgetText  must  be  drawn  in  the
  580.                   highlight text color. NOTE Not  all  gadgets  support this
  581.                   switch.
  582.  
  583.  Text Place     » This cycle gadget  determines  where that  gadget  text is
  584.                   placed. The possibilities are IN, LEFT,  RIGHT,  ABOVE and
  585.                   BELOW. NOTE: Only the Button gadget supports IN.
  586.  
  587.  OK             » This  gadget  will  add  the  gadget  with   the  selected
  588.                   specifics to the edit window or set the desired changes.
  589.  
  590.  CANCEL         » This will cancel the operation.
  591.  
  592.  Following is a description of the extra specifics  of the  different gadget
  593.  kinds supported by GadToolsBox.
  594.  
  595.  »»» 9.1) The CheckBox Gadget
  596.  
  597.  Checked       » When this gadget is switched on it tells that the gadget is
  598.                  checked by default.
  599.  
  600.  »»» 9.2) The Integer Gadget
  601.  
  602.  MaxChars      » You must type the maximum possible digits plus one that may
  603.                  be typed in the gadget. NOTE: This cannot be smaller than 2
  604.  
  605.  Number        » Type the default number in this gadget  that the  resulting
  606.                  gadget has in it.
  607.  
  608.  »»» 9.3) The ListView Gadget
  609.  
  610.  Read Only     » When this gadget is selected the  ListView  Gadget  will be
  611.                  read-only. NOTE: The ListView will only be read-only in the
  612.                  generated source.
  613.  
  614.  ShowSelected  » When this gadget is selected the active (clicked)  entry in
  615.                  the listview gadget will be shown below the listview gadget
  616.                  NOTE: This option is only available  if the ListView  isn't
  617.                  ReadOnly.
  618.  
  619.  Spacing       » Type the  extra  number  of  pixels  GadTools  must  insert
  620.                  between the listview entries. NOTE: This  value  cannot  be
  621.                  smaller than 0.
  622.  
  623.  Scr. Width    » Type the width of the scroller gadget next to the  ListView
  624.                  gadget in here. NOTE: This value may not be smaller than 16
  625.  
  626.  Labels        » This is a ListView Gadget combined with a string gadget. In
  627.                  the  string  gadget  you can  type  the  entries  that  the
  628.                  listview must have. To edit an entry you  must first  click
  629.                  on the entry in the listview and then edit the entry in the
  630.                  string  gadget.  NOTE:  The  "!!ACTION GADGET!!"  entry  is
  631.                  always in the list and cannot  be removed  or edited.  This
  632.                  entry is necessary to keep the ListView  selectable  in the
  633.                  program. This entry will ofcourse not showup in  the source
  634.                  generated.
  635.  
  636.  ^ Remove ^    » This gadget enables you to remove  entries  from the  list.
  637.                  Just click on the entry in the ListView gadget and  then on
  638.                  this gadget and the entry is gone.
  639.  
  640.  »»» 9.4) The Mx Gadget
  641.  
  642.  Spacing       » In this gadget you can  type the  spacing  in  pixels  that
  643.                  GadTools should insert between the items of the  MX gadget.
  644.  
  645.  Labels        » This is a ListView Gadget combined with a string gadget. In
  646.                  the  string  gadget  you can  type  the  entries  that  the
  647.                  mx must have.  To  edit  an  entry  you  must  first  click
  648.                  on the entry in the listview and then edit the entry in the
  649.                  string  gadget.  NOTE:  You must enter atleast two  entries
  650.                  for the MX gadget.
  651.  
  652.  ^ Remove ^    » This gadget enables you to remove  entries  from the  list.
  653.                  Just click on the entry in the ListView gadget and  then on
  654.                  this gadget and the entry is gone.
  655.  
  656.  »»» 9.5) The Cycle Gadget
  657.  
  658.  Labels        » This is a ListView Gadget combined with a string gadget. In
  659.                  the  string  gadget  you can  type  the  entries  that  the
  660.                  cycle must have.  To edit an  entry you  must  first  click
  661.                  on the entry in the listview and then edit the entry in the
  662.                  string  gadget.  NOTE:  You must enter atleast two  entries
  663.                  for the Cycle gadget.
  664.  
  665.  ^ Remove ^    » This gadget enables you to remove  entries  from the  list.
  666.                  Just click on the entry in the ListView gadget and  then on
  667.                  this gadget and the entry is gone.
  668.  
  669.  »»» 9.6) The Palette Gadget
  670.  
  671.  Width         » In  this  gadget  you  can  type  the  width  of  the color
  672.                  indicator if you want one on the left of the gadget.  NOTE:
  673.                  any value smaller than 9 will indicate that you do not want
  674.                  a color indicator.
  675.  
  676.  Height        » In  this  gadget  you  can  type  the height  of  the color
  677.                  indicator if you want one above the gadget. NOTE: any value
  678.                  smaller than 9 will indicate that you  do not  want a color
  679.                  indicator.
  680.  
  681.  »»» 9.7) The Scroller Gadget
  682.  
  683.  Immediate     » When   this   gadget  is   selected   you   will  hear  any
  684.                  IDCMP_GADGETDOWN message through the window IDCMP port that
  685.                  this gadget generates.
  686.  
  687.  RelVerify     » When   this   gadget  is   selected   you   will  hear  any
  688.                  IDCMP_GADGETUP  message  through the window IDCMP port that
  689.                  this gadget generates.
  690.  
  691.  Horizontal
  692.  Vertical      » With this gadget you can determine whether this  gadget can
  693.                  be moved horizontally or vertically.
  694.  
  695.  Top           » In this gadget  you  can  type  the  top  of the  area  the
  696.                  scroller is used for.
  697.  
  698.  Total         » In this gadget you  can  type  the  total  of  the area the
  699.                  scroller is used for.
  700.  
  701.  Visible       » In this gadget you  can type  the visible  part of the area
  702.                  this scroller is used for.
  703.  
  704.  Arrows        » In this gadget you can type the size in pixels of an arrow.
  705.                  NOTE: Specifying  a  value smaller  than 8  says you  don't
  706.                  want arrows.
  707.  
  708.  »»» 9.8) The Slider Gadget
  709.  
  710.  Immediate     » When   this   gadget  is   selected   you   will  hear  any
  711.                  IDCMP_GADGETDOWN message through the window IDCMP port that
  712.                  this gadget generates.
  713.  
  714.  RelVerify     » When   this   gadget  is   selected   you   will  hear  any
  715.                  IDCMP_GADGETUP  message  through the window IDCMP port that
  716.                  this gadget generates.
  717.  
  718.  Horizontal
  719.  Vertical      » With this gadget you can determine whether this  gadget can
  720.                  be moved horizontally or vertically.
  721.  
  722.  Min           » In this gadget you can type the minimum value of the slider.
  723.  
  724.  Max           » In this gadget you can type the maximum value of the slider.
  725.  
  726.  Level         » In this gadget you can  type the  initial level  the slider
  727.                  must have.
  728.  
  729.  Level Size    » In  this   gadget  you  can  type  the  maximum  amount  of
  730.                  characters that may be used to print the slider level.
  731.  
  732.  Format        » A formatting string ala RawDoFmt() which  specifies the way
  733.                  the slider level  should be  printed.  NOTE:  When  this is
  734.                  omitted the slider level won't be printed.
  735.  
  736.  Lev. Place    » With this gadget you can specify where GadTools is to print
  737.                  the slider level. The possibilities are LEFT,  RIGHT, ABOVE
  738.                  and below.
  739.  
  740.  »»» 9.9) The String Gadget
  741.  
  742.  MaxChars      » You must type the maximum possible characters plus one that
  743.                  may be typed in the gadget.  NOTE:  This cannot be  smaller
  744.                  than 2.
  745.  
  746.  String        » Type the default string in this gadget  that the  resulting
  747.                  gadget has in it.
  748.  
  749.  »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  750.  » 10) Menu Requesters                                                     »
  751.  »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  752.  GadToolsBox uses three (actually two) windows to let the user edit complete
  753.  menu-strips. Following is a description of those windows.
  754.  
  755.  »»» 10.1) The Menu Requester
  756.  
  757.  This requester is used to edit  the menus.  In the  window you'll  see  the
  758.  following gadgets:
  759.  
  760.  Menus         » This  listview  gadget  contains  the names  of  the  menus
  761.                  currently in memory.  Below this ListView  gadget a  string
  762.                  gadget is  located  which  is used  to  enter/edit the menu
  763.                  names. To add a new menu to  the list  you must  enter it's
  764.                  name in this string gadget and press return. To edit a menu
  765.                  name you must  first  click on  the  name  in  the listview
  766.                  gadget and then edit the name in the string gadget.
  767.  
  768.  Disabled      » This CheckBox gadget tells GadToolsBox whether you want the
  769.                  menu to be disabled or not.
  770.  
  771.  ItemEd        » This gadget must be clicked when you want to add some items
  772.                  to a menu. To do this you must first click on the menu name
  773.                  in the listview gadget which you want to edit items for and
  774.                  then click on this gadget.  If  all goes  well you  will be
  775.                  presented with the "(Sub)Item Requester" (see below).
  776.  
  777.  Delete        » When you want to delete a menu you must click  on it's name
  778.                  in the listview gadget and then click on this gadget.  Then
  779.                  a requester pops up asking for confirmation. NOTE: Deleting
  780.                  a menu with  items  attached to it  will also delete  those
  781.                  items.
  782.  
  783.  DONE          » Clicking on this gadget will close the requester and resume
  784.                  to gadget editing.
  785.  
  786.  »»» 10.1) The (Sub)Item Requester
  787.  
  788.  This requester  is used to  edit  (sub)items  for  a  specific   menu. This
  789.  requester is the same for editing items and subitems. The following gadgets
  790.  are in the window:
  791.  
  792.  (Sub)Items    » This  listview  gadget  contains  the names  of  the  (sub)
  793.                  items currently attached to the menu.  Below  this ListView
  794.                  gadget a string gadget is located  which is used  to  enter
  795.                  /edit the (sub)item names. To add a new  (sub)item  to  the
  796.                  list  you must  enter it's name  in this string  gadget and
  797.                  press return. To edit a menu name you must  first  click on
  798.                  the  name  in  the listview  gadget and then  edit the name
  799.                  in the string gadget.
  800.  
  801.  Checkit       » This will turn the intuition  CHECKIT  flag on/off  for the
  802.                  (sub)item.
  803.  
  804.  Disabled      » This CheckBox gadget tells GadToolsBox whether you want the
  805.                  (sub)item to be disabled or not.
  806.  
  807.  Checked       » This will turn the intuition  CHECKED  flag on/off  for the
  808.                  (sub)item.
  809.  
  810.  MenuToggle    » This will turn the intuition MENUTOGGLE flag on/off for the
  811.                  (sub)item.
  812.  
  813.  ShortCut      » You can  add a  keyboard  shortcut  for  the  (sub)item  by
  814.                  entering the shortcut key in this gadget.
  815.  
  816.  BarLab        » When you click on this gadget a separator bar (NM_BARLABEL)
  817.                  is inserted in the list automatically.
  818.  
  819.  SubEd        »  This  gadget  must be  clicked when  you  want to  add some
  820.                  subitems to a item. To do this you must  first click on the
  821.                  item name in the listview g adget which  you want  to  edit
  822.                  subitems for  and  then  click on  this gadget. If all goes
  823.                  well the requester will switch to  subitems editing.  NOTE:
  824.                  This gadget is disabled  when the  requester already  is in
  825.                  the subitem mode.
  826.  
  827.  Delete        » When you want to delete a (sub)item you must click  on it's
  828.                  name in the listview gadget  and then click on this gadget.
  829.                  Then a requester  pops  up asking  for confirmation.  NOTE:
  830.                  Deleting a item  with  subitems  attached to it  will  also
  831.                  delete those subitems.
  832.  
  833.  DONE          » Clicking on this gadget will  close the  requester and  put
  834.                  you back in the menu requester.
  835.  
  836.  NOTE: There is a possibility to set the MutualExclude  of an item but  this
  837.  has a bug in it which I can't find. When you click on  the (sub)item  which
  838.  must  do  the  excluding and you press the 'x' key you will see the message
  839.  "DRAG-SELECT ITEMS TO EXCLUDE" in the title bar of the item ed window.  Now
  840.  you must click the menu-button of the mouse and go to the menu.  Here's the
  841.  bug..... YOU MUST KEEP THE MOUSE WITH THE RIGHT-BUTTON PRESSED ON  THE MENU
  842.  FOR ABOUT 10-15 SECONDS BEFORE INTUITION  DESIDES TO DROP  THE  MENU ??????
  843.  When the menu is down you must check the items that are to be  excluded and
  844.  the mutual-exclude value will be set. To check several items you must click
  845.  the left-mouse-button on each item whilst  holding  down  the  right mouse-
  846.  button. If you know what  the bug is  please tell me about it so that I can
  847.  fix it.
  848.  
  849.  »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  850.  » 11) The Generated Source                                                »
  851.  »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  852.  The   source  GadToolsBox  generates   contains   complete   routines  that
  853.  opens/locks the screen and allocates/initializes the gadgets and menus  and
  854.  opens the window and prints the text's.  Therefore there  are two  routines
  855.  created. The following globals are  exported when  necessary and  when  the
  856.  generated source isn't static:
  857.  
  858.     xxxWnd          » A pointer to the window
  859.     xxxScr          » A pointer to the screen
  860.     xxxVisualInfo   » A pointer to the screen it's visualinfo
  861.     xxxGList        » A pointer to the created gadgets
  862.     xxxGadgets[..]  » An array of pointers to the created gadgets
  863.     xxxMenus        » A pointer to the created menus
  864.     xxxZoom[4]      » An array of words with the window alternate positions
  865.  
  866.     xxxInitStuf()   » The routine which sets up the stuff
  867.     xxxCleanStuff() » Cleans up all resources used
  868.  
  869.  NOTE: The 'xxx' stands for the Project Prefix which you can enter using the
  870.        preferences requester.
  871.  
  872.  The GadgetID are defined as 'GD_SourceLabel'.  Some of the  above  declared
  873.  data is not always there.  For instance when  you havent  edited any  menus
  874.  the 'xxxMenus' wont  be  generated.   The 'xxxInitStuff()' can  return  the
  875.  following return codes:
  876.  
  877.     0               » Everything is OK
  878.     1               » The screen could not be opened/locked
  879.     2               » GetVisualInfo failed
  880.     3               » A GadgetContext could not be created
  881.     4               » An error occured with the gadget creation
  882.     5               » The window could not be opened
  883.     6               » The menus could not be created
  884.  
  885.  NOTE: When the 'xxxInitStuff()' routine  returns  an  error  you must still
  886.        call 'xxxCleanStuff()' to deallocate/close the resources that did not
  887.        fail to open!
  888.  
  889.  To get a better impression of the generated source you should load/create a
  890.  sample file and generate the source for it. Then  you  can  take  a look to
  891.  what was generated.
  892.  
  893.  »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  894.  » 12) Notes                                                               »
  895.  »»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»»
  896.  At this time there really isn't much to say about the program. It is a tool
  897.  that  will  ( or atleast should )  save  you a lot  of time  in creating  a
  898.  GadTools user interface for your programs.  I  really  don't know  how  the
  899.  program reacts under low memory conditions because no testing has been done
  900.  under these conditions  ( what  can  I say....  I'm lazy... ).
  901.  
  902.  Bug reports,  suggestions,  postcards,  flames,  criticism,  contributions,
  903.  ideas, gifts, etc., etc., etc........... to:
  904.  
  905.  Jan van den Baard          Fido: 2:500/29 (Jan van.den.Baard)
  906.  Bakkerstraat 176
  907.  3082 HE, Rotterdam
  908.  Holland
  909.